function
<new>

operator delete[]

ordinary (1)
void operator delete[] (void* ptr) throw();
nothrow (2)
void operator delete[] (void* ptr, const std::nothrow_t& nothrow_constant) throw();
placement (3)
void operator delete[] (void* ptr, void* voidptr2) throw();
ordinary (1)
void operator delete[] (void* ptr) noexcept;
nothrow (2)
void operator delete[] (void* ptr, const std::nothrow_t& nothrow_constant) noexcept;
placement (3)
void operator delete[] (void* ptr, void* voidptr2) noexcept;
ordinary (1)
void operator delete[] (void* ptr) noexcept;
nothrow (2)
void operator delete[] (void* ptr, const std::nothrow_t& nothrow_constant) noexcept;
placement (3)
void operator delete[] (void* ptr, void* voidptr2) noexcept;
with size (4)
void operator delete[] (void* ptr, std::size_t size) noexcept;
nothrow with size (5)
void operator delete[] (void* ptr, std::size_t size,
                        const std::nothrow_t& nothrow_constant) noexcept;
Deallocate storage space of array
Default deallocation functions (array form).

(1) ordinary delete
Deallocates the memory block pointed to by ptr (if not null), releasing the storage space previously allocated to it by a call to operator new[] and rendering that pointer location invalid.
(2) nothrow delete
Same as above (1).
(3) placement delete
Does nothing.
(1) ordinary delete
Deallocates the memory block pointed to by ptr (if not null), releasing the storage space previously allocated to it by a call to operator new[] and rendering that pointer location invalid.
The default definition calls ::operator delete(ptr).
(2) nothrow delete
Same as above (1).
The default definition calls the first version (1): ::operator delete[](ptr).
(3) placement delete
Does nothing.
(1) ordinary delete
Deallocates the memory block pointed to by ptr (if not null), releasing the storage space previously allocated to it by a call to operator new[] and rendering that pointer location invalid.
The default definition calls ::operator delete(ptr).
(2) nothrow delete
Same as above (1).
The default definition calls the first version (1): ::operator delete[](ptr).
(3) placement delete
Does nothing.
(4) (5) with size
Same as (1) and (2) respectivelly.
The default definition simply calls the corresponding version: either (1) or (2).
They provide an optimization point for custom implementations: they are called with the same size argument used in the call to the corresponding operator new[]|allocation function.

The default allocation and deallocation functions are special components of the standard library; They have the following unique properties:
  • Global: All three versions of operator delete[] are declared in the global namespace, not within the std namespace.
  • Implicit: The deallocating versions (i.e., all but (3)) are implicitly declared in every translation unit of a C++ program, no matter whether header <new> is included or not.
  • Replaceable: The deallocating versions (i.e., all but (3)) are also replaceable: A program may provide its own definition that replaces the one provided by default to produce the result described above, or can overload it for specific types.

operator delete[] is a regular function that can be called explicitly just as any other function. But in C++, delete[] is an operator with a very specific behavior: An expression with the delete[] operator, first calls the appropriate destructors for each element in the array (if these are of a class type), and then calls an array deallocation function.

The array deallocation function for a class object is a member function named operator delete[], if it exists. In all other cases it is a global function operator delete[] (i.e., this function -- or a more specific overload). If the delete[] expression is preceded by the scope operator (i.e., ::operator delete[]), only global array deallocation functions are considered.

delete[] expressions that use global array deallocation functions, always call single-argument signatures (such as (1)).
delete[] expressions that use global array deallocation functions always use the signature that takes either a pointer (such as (1)), or a pointer and a size (such as (4)). Preferring always the version with size (4), unless an overload provides a better match for the pointer type.

The other signatures ((2) and (3)) are never called by a delete[]-expression (the delete[] operator always calls the ordinary version of this function, and exactly once for each of its arguments). These other signatures are only called automatically by a new[]-expression when their object construction fails (e.g., if the constructor of an object throws while being constructed by a new[]-expression with nothrow, the matching operator delete[] function accepting a nothrow argument is called).

Non-member array deallocation functions shall not be declared in a namespace scope other than the global namespace.

Parameters

ptr
A pointer to the memory block to be released, type-casted to a void*.
If this is a null-pointer, the function does nothing.
Otherwise, this pointer value should have been returned by a previous call to operator new[], and have not yet been released by a previous call to this function.
Otherwise, this pointer value should have been returned by a previous call to operator new[], and have not yet been released by a previous call to this function.
If the implementation has strict pointer safety, this pointer shall also be a safely-derived pointer.
nothrow_constant
The constant nothrow. This parameter is ignored in the default definition.
nothrow_t is the type of constant nothrow.
voidptr2
A void pointer. The value is ignored in the default definition.
size
The first argument passed to the allocation function when the memory block was allocated.
std::size_t is an unsigned integral type.

Return value

none

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
// operator delete[] example
#include <iostream>     // std::cout

struct MyClass {
  MyClass() {std::cout <<"MyClass constructed\n";}
  ~MyClass() {std::cout <<"MyClass destroyed\n";}
};

int main () {
  MyClass * pt;

  pt = new MyClass[3];
  delete[] pt;

  return 0;
}


Output:

myclass constructed
myclass constructed
myclass constructed
myclass destroyed
myclass destroyed
myclass destroyed

Data races

Modifies the storage referenced by ptr.
Calls to allocation and deallocation functions that reuse the same unit of storage shall occur in a single total order where each deallocation happens before the next allocation.
This shall also apply to the observable behavior of custom replacements for this function.

Exception safety

No-throw guarantee: this function never throws exceptions.

Notice that an invalid value of ptr causes undefined behavior.
Notice that either an invalid value of ptr, or a value for size that does not match the one passed to the allocation function, causes undefined behavior.

See also

operator new[]
Allocate storage space for array (function )
operator delete
Deallocate storage space (function )